package org.xyl.service;

import dev.langchain4j.data.embedding.Embedding;
import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.store.embedding.EmbeddingMatch;

import java.util.List;
import java.util.Map;

/**
 * 向量库服务接口
 * 提供向量库的创建、查询、管理等功能
 */
public interface VectorLibraryServiceInterface {

    /**
     * 创建向量库
     * @param libraryName 向量库名称
     * @return 是否创建成功
     */
    boolean createVectorLibrary(String libraryName);

    /**
     * 在指定向量库中搜索相关文档
     * @param libraryName 向量库名称
     * @param queryEmbedding 查询嵌入向量
     * @param topK 返回前K个最相关的结果
     * @return 相关文档匹配列表
     */
    List<EmbeddingMatch<TextSegment>> searchInVectorLibrary(String libraryName, Embedding queryEmbedding, int topK);

    /**
     * 将文档添加到向量库
     * @param libraryName 向量库名称
     * @param document 文档内容
     * @param metadata 文档元数据
     */
    void addDocumentToLibrary(String libraryName, String document, Map<String, Object> metadata);

    /**
     * 删除向量库
     * @param libraryName 向量库名称
     * @return 是否删除成功
     */
    boolean deleteVectorLibrary(String libraryName);

    /**
     * 获取向量库列表
     * @return 可用的向量库名称列表
     */
    List<String> listVectorLibraries();

    /**
     * 获取向量库统计信息
     * @param libraryName 向量库名称
     * @return 统计信息
     */
    Map<String, Object> getVectorLibraryStats(String libraryName);

    /**
     * 在向量库中搜索（基于查询文本）
     * @param libraryName 向量库名称
     * @param query 查询文本
     * @param maxResults 返回结果数量
     * @return 相关文档匹配列表
     */
    List<EmbeddingMatch<TextSegment>> searchInLibrary(String libraryName, String query, int maxResults);
}